<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Sink frontends</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Log v2">
<link rel="up" href="../detailed.html" title="Detailed features description">
<link rel="prev" href="sources.html" title="Logging sources">
<link rel="next" href="sink_backends.html" title="Sink backends">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr><td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td></tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="sources.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../detailed.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="sink_backends.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="log.detailed.sink_frontends"></a><a class="link" href="sink_frontends.html" title="Sink frontends">Sink frontends</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.basic_services">Basic sink
        frontend services</a></span></dt>
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.unlocked">Unlocked sink
        frontend</a></span></dt>
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.sync">Synchronous sink
        frontend</a></span></dt>
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.async">Asynchronous sink
        frontend</a></span></dt>
</dl></div>
<p>
        Sink frontends are the part of sinks provided by the library, that implements
        the common functionality shared between all sinks. This includes support
        for filtering, exception handling and thread synchronization. Also, since
        formatting is typical for text-based sinks, it is implemented by frontends
        as well. Every sink frontend receives log records from the logging core and
        then passes them along to the associated sink backend. The frontend does
        not define how to process records but rather in what way the core should
        interact with the backend. It is the backend that defines the processing
        rules of the log records. You probably won't have to write your own frontend
        when you need to create a new type of sink, because the library provides
        a number of frontends that cover most use cases.
      </p>
<p>
        Sink frontends derive from the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/sink.html" title="Class sink">sink</a></code>
        class template, which is used by the logging core to supply log records.
        Technically speaking, one can derive his class from the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/sink.html" title="Class sink">sink</a></code>
        template and have his new-found sink, but using sink frontends saves from
        quite an amount of routine work. As every sink frontend is associated with
        a backend, the corresponding backend will also be constructed by the frontend
        upon its construction (unless the user provides the backend instance himself),
        making the sink complete. Therefore, when the frontend is constructed it
        can be registered in the logging core to begin processing records. See the
        <a class="link" href="sink_backends.html" title="Sink backends">Sink Backends</a> section for
        more details on interactions between frontends and backends.
      </p>
<p>
        Below is a more detailed overview of the services provided by sink frontends.
      </p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="log.detailed.sink_frontends.basic_services"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.basic_services" title="Basic sink frontend services">Basic sink
        frontend services</a>
</h4></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.basic_services.filtering">Filtering</a></span></dt>
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.basic_services.formatting">Formatting</a></span></dt>
<dt><span class="section"><a href="sink_frontends.html#log.detailed.sink_frontends.basic_services.exception_handling">Exception
          handling</a></span></dt>
</dl></div>
<p>
          There are a number of basic functionalities that all sink frontends provide.
        </p>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="log.detailed.sink_frontends.basic_services.filtering"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.basic_services.filtering" title="Filtering">Filtering</a>
</h5></div></div></div>
<p>
            All sink frontends support filtering. The user can specify a custom filtering
            function object or a filter constructed with the <a class="link" href="expressions.html" title="Lambda expressions">library-provided
            tools</a>. The filter can be set with the <code class="computeroutput"><span class="identifier">set_filter</span></code>
            method or cleared with the <code class="computeroutput"><span class="identifier">reset_filter</span></code>
            method. The filter is invoked during the call to the <code class="computeroutput"><span class="identifier">will_consume</span></code>
            method that is issued by the logging core. If the filter is not set,
            it is assumed that the sink will accept any log record.
          </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              Like the logging core, all sink frontends assume it is safe to call
              filters from multiple threads concurrently. This is fine with the library-provided
              filters.
            </p></td></tr>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="log.detailed.sink_frontends.basic_services.formatting"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.basic_services.formatting" title="Formatting">Formatting</a>
</h5></div></div></div>
<p>
            For text-based sink backends, frontends implement record formatting.
            Like with filters, <a class="link" href="expressions.html" title="Lambda expressions">lambda expressions</a>
            can be used to construct formatters. The formatter can be set for a text-based
            sink by calling the <code class="computeroutput"><span class="identifier">set_formatter</span></code>
            method or cleared by calling <code class="computeroutput"><span class="identifier">reset_formatter</span></code>.
          </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h5 class="title">
<a name="log.detailed.sink_frontends.basic_services.exception_handling"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.basic_services.exception_handling" title="Exception handling">Exception
          handling</a>
</h5></div></div></div>
<p>
            All sink frontends allow setting up exception handlers in order to customize
            error processing on a per-sink basis. One can install an exception handling
            function with the <code class="computeroutput"><span class="identifier">set_exception_handler</span></code>
            method, this function will be called with no arguments from a <code class="computeroutput"><span class="keyword">catch</span></code> block if an exception occurs during
            record processing in the backend or during the sink-specific filtering.
            The exception handler is free to rethrow an exception or to suppress
            it. In the former case the exception is propagated to the core, where
            another layer of exception handling can come into action.
          </p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
              <a class="link" href="../detailed.html#log.detailed.core.core.exception_handling" title="Exception handling">Logging core</a>
              and <a class="link" href="sources.html#log.detailed.sources.exception_handling" title="Loggers with exception handling support">loggers</a>
              also support installing exception handlers.
            </p></td></tr>
</table></div>
<p>
            The library provides a <a class="link" href="utilities.html#log.detailed.utilities.exception_handlers" title="Exception handlers">convenient
            tool</a> for dispatching exceptions into a unary polymorphic function
            object.
          </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              An exception handler is not allowed to return a value. This means you
              are not able to alter the filtering result once an exception occurs,
              and thus filtering will always fail.
            </p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
              All sink frontends assume it is safe to call exception handlers from
              multiple threads concurrently. This is fine with the library-provided
              exception dispatchers.
            </p></td></tr>
</table></div>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="log.detailed.sink_frontends.unlocked"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.unlocked" title="Unlocked sink frontend">Unlocked sink
        frontend</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.unlocked_frontend_hpp" title="Header &lt;boost/log/sinks/unlocked_frontend.hpp&gt;">boost/log/sinks/unlocked_frontend.hpp</a></code><span class="special">&gt;</span>
</pre>
<p>
          The unlocked sink frontend is implemented with the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unlocked_sink.html" title="Class template unlocked_sink">unlocked_sink</a></code>
          class template. This frontend provides the most basic service for the backend.
          The <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unlocked_sink.html" title="Class template unlocked_sink">unlocked_sink</a></code>
          frontend performs no thread synchronization when accessing the backend,
          assuming that synchronization either is not needed or is implemented by
          the backend. Nevertheless, setting up a filter is still thread-safe (that
          is, one can safely change the filter in the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unlocked_sink.html" title="Class template unlocked_sink">unlocked_sink</a></code>
          frontend while other threads are writing logs through this sink). This
          is the only sink frontend available in a single threaded environment. The
          example of use is as follows:
        </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">severity_level</span>
<span class="special">{</span>
    <span class="identifier">normal</span><span class="special">,</span>
    <span class="identifier">warning</span><span class="special">,</span>
    <span class="identifier">error</span>
<span class="special">};</span>

<span class="comment">// A trivial sink backend that requires no thread synchronization</span>
<span class="keyword">class</span> <span class="identifier">my_backend</span> <span class="special">:</span>
    <span class="keyword">public</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">basic_sink_backend</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">concurrent_feeding</span> <span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">public</span><span class="special">:</span>
    <span class="comment">// The function is called for every log record to be written to log</span>
    <span class="keyword">void</span> <span class="identifier">consume</span><span class="special">(</span><span class="identifier">logging</span><span class="special">::</span><span class="identifier">record_view</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">rec</span><span class="special">)</span>
    <span class="special">{</span>
        <span class="comment">// We skip the actual synchronization code for brevity</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">rec</span><span class="special">[</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">smessage</span><span class="special">]</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="special">}</span>
<span class="special">};</span>

<span class="comment">// Complete sink type</span>
<span class="keyword">typedef</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">unlocked_sink</span><span class="special">&lt;</span> <span class="identifier">my_backend</span> <span class="special">&gt;</span> <span class="identifier">sink_t</span><span class="special">;</span>

<span class="keyword">void</span> <span class="identifier">init_logging</span><span class="special">()</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// The simplest way, the backend is default-constructed</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">sink1</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">sink_t</span><span class="special">());</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">add_sink</span><span class="special">(</span><span class="identifier">sink1</span><span class="special">);</span>

    <span class="comment">// One can construct backend separately and pass it to the frontend</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">my_backend</span> <span class="special">&gt;</span> <span class="identifier">backend</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">my_backend</span><span class="special">());</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">sink2</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">sink_t</span><span class="special">(</span><span class="identifier">backend</span><span class="special">));</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">add_sink</span><span class="special">(</span><span class="identifier">sink2</span><span class="special">);</span>

    <span class="comment">// You can manage filtering through the sink interface</span>
    <span class="identifier">sink1</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="identifier">warning</span><span class="special">);</span>
    <span class="identifier">sink2</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="special">&gt;(</span><span class="string">"Channel"</span><span class="special">)</span> <span class="special">==</span> <span class="string">"net"</span><span class="special">);</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<p>
          <a href="../../../../../../libs/log/example/doc/sinks_unlocked.cpp" target="_top">See the complete
          code</a>.
        </p>
<p>
          All sink backends provided by the library require thread synchronization
          on the frontend part. If we tried to instantiate the frontend on the backend
          that requires more strict threading guarantees than what the frontend provides,
          the code wouldn't have compiled. Therefore this frontend is mostly useful
          in single-threaded environments and with custom backends.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="log.detailed.sink_frontends.sync"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.sync" title="Synchronous sink frontend">Synchronous sink
        frontend</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.sync_frontend_hpp" title="Header &lt;boost/log/sinks/sync_frontend.hpp&gt;">boost/log/sinks/sync_frontend.hpp</a></code><span class="special">&gt;</span>
</pre>
<p>
          The synchronous sink frontend is implemented with the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/synchronous_sink.html" title="Class template synchronous_sink">synchronous_sink</a></code>
          class template. It is similar to the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unlocked_sink.html" title="Class template unlocked_sink">unlocked_sink</a></code>
          but additionally provides thread synchronization with a mutex before passing
          log records to the backend. All sink backends that support formatting currently
          require thread synchronization in the frontend.
        </p>
<p>
          The synchronous sink also introduces the ability to acquire a pointer to
          the locked backend. As long as the pointer exists, the backend is guaranteed
          not to be accessed from other threads, unless the access is done through
          another frontend or a direct reference to the backend. This feature can
          be useful if there is a need to perform some updates on the sink backend
          while other threads may be writing logs. Beware, though, that while the
          backend is locked any other thread that tries to write a log record to
          the sink gets blocked until the backend is released.
        </p>
<p>
          The usage is similar to the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unlocked_sink.html" title="Class template unlocked_sink">unlocked_sink</a></code>.
        </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">severity_level</span>
<span class="special">{</span>
    <span class="identifier">normal</span><span class="special">,</span>
    <span class="identifier">warning</span><span class="special">,</span>
    <span class="identifier">error</span>
<span class="special">};</span>

<span class="comment">// Complete sink type</span>
<span class="keyword">typedef</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">synchronous_sink</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span> <span class="identifier">sink_t</span><span class="special">;</span>

<span class="keyword">void</span> <span class="identifier">init_logging</span><span class="special">()</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// Create a backend and initialize it with a stream</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span> <span class="identifier">backend</span> <span class="special">=</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;();</span>
    <span class="identifier">backend</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="special">&gt;(&amp;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">null_deleter</span><span class="special">()));</span>

    <span class="comment">// Wrap it into the frontend and register in the core</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">sink</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">sink_t</span><span class="special">(</span><span class="identifier">backend</span><span class="special">));</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">add_sink</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>

    <span class="comment">// You can manage filtering and formatting through the sink interface</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="identifier">warning</span><span class="special">);</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_formatter</span>
    <span class="special">(</span>
        <span class="identifier">expr</span><span class="special">::</span><span class="identifier">stream</span>
            <span class="special">&lt;&lt;</span> <span class="string">"Level: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span>
            <span class="special">&lt;&lt;</span> <span class="string">" Message: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">smessage</span>
    <span class="special">);</span>

    <span class="comment">// You can also manage backend in a thread-safe manner</span>
    <span class="special">{</span>
        <span class="identifier">sink_t</span><span class="special">::</span><span class="identifier">locked_backend_ptr</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">locked_backend</span><span class="special">();</span>
        <span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ofstream</span> <span class="special">&gt;(</span><span class="string">"sample.log"</span><span class="special">));</span>
    <span class="special">}</span> <span class="comment">// the backend gets released here</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<p>
          <a href="../../../../../../libs/log/example/doc/sinks_sync.cpp" target="_top">See the complete
          code</a>.
        </p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="log.detailed.sink_frontends.async"></a><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.async" title="Asynchronous sink frontend">Asynchronous sink
        frontend</a>
</h4></div></div></div>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.async_frontend_hpp" title="Header &lt;boost/log/sinks/async_frontend.hpp&gt;">boost/log/sinks/async_frontend.hpp</a></code><span class="special">&gt;</span>

<span class="comment">// Related headers</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.unbounded_fifo_queue_hpp" title="Header &lt;boost/log/sinks/unbounded_fifo_queue.hpp&gt;">boost/log/sinks/unbounded_fifo_queue.hpp</a></code><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.unbounded_ordering_queue_hpp" title="Header &lt;boost/log/sinks/unbounded_ordering_queue.hpp&gt;">boost/log/sinks/unbounded_ordering_queue.hpp</a></code><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.bounded_fifo_queue_hpp" title="Header &lt;boost/log/sinks/bounded_fifo_queue.hpp&gt;">boost/log/sinks/bounded_fifo_queue.hpp</a></code><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.bounded_ordering_queue_hpp" title="Header &lt;boost/log/sinks/bounded_ordering_queue.hpp&gt;">boost/log/sinks/bounded_ordering_queue.hpp</a></code><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.drop_on_overflow_hpp" title="Header &lt;boost/log/sinks/drop_on_overflow.hpp&gt;">boost/log/sinks/drop_on_overflow.hpp</a></code><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><code class="computeroutput"><a class="link" href="../../sinks.html#header.boost.log.sinks.block_on_overflow_hpp" title="Header &lt;boost/log/sinks/block_on_overflow.hpp&gt;">boost/log/sinks/block_on_overflow.hpp</a></code><span class="special">&gt;</span>
</pre>
<p>
          The frontend is implemented in the <code class="computeroutput"><a class="link" href="../../boost/log/sinks/asynchronous_sink.html" title="Class template asynchronous_sink">asynchronous_sink</a></code>
          class template. Like the synchronous one, asynchronous sink frontend provides
          a way of synchronizing access to the backend. All log records are passed
          to the backend in a dedicated thread, which makes it suitable for backends
          that may block for a considerable amount of time (network and other hardware
          device-related sinks, for example). The internal thread of the frontend
          is spawned on the frontend constructor and joined on its destructor (which
          implies that the frontend destruction may block).
        </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            The current implementation of the asynchronous sink frontend use record
            queueing. This introduces a certain latency between the fact of record
            emission and its actual processing (such as writing into a file). This
            behavior may be inadequate in some contexts, such as debugging an application
            that is prone to crashes.
          </p></td></tr>
</table></div>
<p>
</p>
<pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">severity_level</span>
<span class="special">{</span>
    <span class="identifier">normal</span><span class="special">,</span>
    <span class="identifier">warning</span><span class="special">,</span>
    <span class="identifier">error</span>
<span class="special">};</span>

<span class="comment">// Complete sink type</span>
<span class="keyword">typedef</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">asynchronous_sink</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span> <span class="identifier">sink_t</span><span class="special">;</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">init_logging</span><span class="special">()</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// Create a backend and initialize it with a stream</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span> <span class="identifier">backend</span> <span class="special">=</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;();</span>
    <span class="identifier">backend</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="special">&gt;(&amp;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">null_deleter</span><span class="special">()));</span>

    <span class="comment">// Wrap it into the frontend and register in the core</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">sink</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">sink_t</span><span class="special">(</span><span class="identifier">backend</span><span class="special">));</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">add_sink</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>

    <span class="comment">// You can manage filtering and formatting through the sink interface</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="identifier">warning</span><span class="special">);</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_formatter</span>
    <span class="special">(</span>
        <span class="identifier">expr</span><span class="special">::</span><span class="identifier">stream</span>
            <span class="special">&lt;&lt;</span> <span class="string">"Level: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span>
            <span class="special">&lt;&lt;</span> <span class="string">" Message: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">message</span>
    <span class="special">);</span>

    <span class="comment">// You can also manage backend in a thread-safe manner</span>
    <span class="special">{</span>
        <span class="identifier">sink_t</span><span class="special">::</span><span class="identifier">locked_backend_ptr</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">locked_backend</span><span class="special">();</span>
        <span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ofstream</span> <span class="special">&gt;(</span><span class="string">"sample.log"</span><span class="special">));</span>
    <span class="special">}</span> <span class="comment">// the backend gets released here</span>

    <span class="keyword">return</span> <span class="identifier">sink</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<div class="important"><table border="0" summary="Important">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
<th align="left">Important</th>
</tr>
<tr><td align="left" valign="top"><p>
            If asynchronous logging is used in a multi-module application, one should
            decide carefully when to unload dynamically loaded modules that write
            logs. The library has many places where it may end up using resources
            that reside in the dynamically loaded module. Examples of such resources
            are virtual tables, string literals and functions. If any of these resources
            are still used by the library when the module in which they reside gets
            unloaded, the application will most likely crash. Strictly speaking,
            this problem exists with any sink type (and is not limited to sinks in
            the first place), but asynchronous sinks introduce an additional problem.
            One cannot tell which resources are used by the asynchronous sink because
            it works in a dedicated thread and uses buffered log records. There is
            no general solution for this issue. Users are advised to either avoid
            dynamic module unloading during the application's work time, or to avoid
            asynchronous logging. As an additional way to cope with the problem,
            one may try to shutdown all asynchronous sinks before unloading any modules,
            and after unloading re-create them. However, avoiding dynamic unloading
            is the only way to solve the problem completely.
          </p></td></tr>
</table></div>
<p>
          In order to stop the dedicated thread feeding log records to the backend
          one can call the <code class="computeroutput"><span class="identifier">stop</span></code> method
          of the frontend. This method will be called automatically in the frontend
          destructor. The <code class="computeroutput"><span class="identifier">stop</span></code> method,
          unlike thread interruption, will only terminate the feeding loop when a
          log record that is being fed is processed by the backend (i.e. it will
          not interrupt the record processing that has already started). However,
          it may happen that some records are still left in the queue after returning
          from the <code class="computeroutput"><span class="identifier">stop</span></code> method. In
          order to flush them to the backend an additional call to the <code class="computeroutput"><span class="identifier">feed_records</span></code> method is required. This
          is useful in the application termination stage.
        </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">stop_logging</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;&amp;</span> <span class="identifier">sink</span><span class="special">)</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// Remove the sink from the core, so that no records are passed to it</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">remove_sink</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>

    <span class="comment">// Break the feeding loop</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">stop</span><span class="special">();</span>

    <span class="comment">// Flush all log records that may have left buffered</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">flush</span><span class="special">();</span>

    <span class="identifier">sink</span><span class="special">.</span><span class="identifier">reset</span><span class="special">();</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<p>
          <a href="../../../../../../libs/log/example/doc/sinks_async.cpp" target="_top">See the complete
          code</a>.
        </p>
<p>
          Spawning the dedicated thread for log record feeding can be suppressed
          with the optional boolean <code class="computeroutput"><span class="identifier">start_thread</span></code>
          named parameter of the frontend. In this case the user can select either
          way of processing records:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              Call the <code class="computeroutput"><span class="identifier">run</span></code> method
              of the frontend. This call will block in the feeding loop. This loop
              can be interrupted with the call to <code class="computeroutput"><span class="identifier">stop</span></code>.
            </li>
<li class="listitem">
              Periodically call <code class="computeroutput"><span class="identifier">feed_records</span></code>.
              This method will process all the log records that were in the frontend
              queue when the call was issued and then return.
            </li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            Users should take care not to mix these two approaches concurrently.
            Also, none of these methods should be called if the dedicated feeding
            thread is running (i.e., the <code class="computeroutput"><span class="identifier">start_thread</span></code>
            was not specified in the construction or had the value of <code class="computeroutput"><span class="keyword">true</span></code>.
          </p></td></tr>
</table></div>
<h6>
<a name="log.detailed.sink_frontends.async.h0"></a>
          <span class="phrase"><a name="log.detailed.sink_frontends.async.customizing_record_queueing_strategy"></a></span><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.async.customizing_record_queueing_strategy">Customizing
          record queueing strategy</a>
        </h6>
<p>
          The <code class="computeroutput"><a class="link" href="../../boost/log/sinks/asynchronous_sink.html" title="Class template asynchronous_sink">asynchronous_sink</a></code>
          class template can be customized with the record queueing strategy. Several
          strategies are provided by the library:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unbounded_fifo_queue.html" title="Class unbounded_fifo_queue">unbounded_fifo_queue</a></code>.
              This strategy is the default. As the name implies, the queue is not
              limited in depth and does not order log records.
            </li>
<li class="listitem">
              <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unbounded_ordering_queue.html" title="Class template unbounded_ordering_queue">unbounded_ordering_queue</a></code>.
              Like <code class="computeroutput"><a class="link" href="../../boost/log/sinks/unbounded_fifo_queue.html" title="Class unbounded_fifo_queue">unbounded_fifo_queue</a></code>,
              the queue has unlimited depth but it applies an order on the queued
              records. We will return to ordering queues in a moment.
            </li>
<li class="listitem">
              <code class="computeroutput"><a class="link" href="../../boost/log/sinks/bounded_fifo_queue.html" title="Class template bounded_fifo_queue">bounded_fifo_queue</a></code>.
              The queue has limited depth specified in a template parameter as well
              as the overflow handling strategy. No record ordering is applied.
            </li>
<li class="listitem">
              <code class="computeroutput"><a class="link" href="../../boost/log/sinks/bounded_ordering_queue.html" title="Class template bounded_ordering_queue">bounded_ordering_queue</a></code>.
              Like <code class="computeroutput"><a class="link" href="../../boost/log/sinks/bounded_fifo_queue.html" title="Class template bounded_fifo_queue">bounded_fifo_queue</a></code>
              but also applies log record ordering.
            </li>
</ul></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
            Be careful with unbounded queueing strategies. Since the queue has unlimited
            depth, if log records are continuously generated faster than being processed
            by the backend the queue grows uncontrollably which manifests itself
            as a memory leak.
          </p></td></tr>
</table></div>
<p>
          Bounded queues support the following overflow strategies:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              <code class="computeroutput"><a class="link" href="../../boost/log/sinks/drop_on_overflow.html" title="Class drop_on_overflow">drop_on_overflow</a></code>.
              When the queue is full, silently drop excessive log records.
            </li>
<li class="listitem">
              <code class="computeroutput"><a class="link" href="../../boost/log/sinks/block_on_overflow.html" title="Class block_on_overflow">block_on_overflow</a></code>.
              When the queue is full, block the logging thread until the backend
              feeding thread manages to process some of the queued records.
            </li>
</ul></div>
<p>
          For example, this is how we could modify the previous example to limit
          the record queue to 100 elements:
        </p>
<p>
</p>
<pre class="programlisting"><span class="comment">// Complete sink type</span>
<span class="keyword">typedef</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">asynchronous_sink</span><span class="special">&lt;</span>
    <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span><span class="special">,</span>
    <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">bounded_fifo_queue</span><span class="special">&lt;</span>                                                   <a class="co" name="log.detailed.sink_frontends.async.c0" href="sink_frontends.html#log.detailed.sink_frontends.async.c1"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
        <span class="number">100</span><span class="special">,</span>                                                                     <a class="co" name="log.detailed.sink_frontends.async.c2" href="sink_frontends.html#log.detailed.sink_frontends.async.c3"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
        <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">drop_on_overflow</span>                                                  <a class="co" name="log.detailed.sink_frontends.async.c4" href="sink_frontends.html#log.detailed.sink_frontends.async.c5"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
    <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">sink_t</span><span class="special">;</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">init_logging</span><span class="special">()</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// Create a backend and initialize it with a stream</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span> <span class="identifier">backend</span> <span class="special">=</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;();</span>
    <span class="identifier">backend</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="special">&gt;(&amp;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">null_deleter</span><span class="special">()));</span>

    <span class="comment">// Wrap it into the frontend and register in the core</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">sink</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">sink_t</span><span class="special">(</span><span class="identifier">backend</span><span class="special">));</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">add_sink</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>

    <span class="comment">// ...</span>

    <span class="keyword">return</span> <span class="identifier">sink</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c1"></a><a href="#log.detailed.sink_frontends.async.c0"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              log record queueing strategy
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c3"></a><a href="#log.detailed.sink_frontends.async.c2"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              record queue capacity
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c5"></a><a href="#log.detailed.sink_frontends.async.c4"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              overflow handling policy
            </p></td>
</tr>
</table></div>
<p>
          <a href="../../../../../../libs/log/example/doc/sinks_async_bounded.cpp" target="_top">See the
          complete code</a>.
        </p>
<p>
          Also see the <a href="../../../../../../libs/log/example/bounded_async_log/main.cpp" target="_top"><code class="computeroutput"><span class="identifier">bounded_async_log</span></code></a> example in
          the library distribution.
        </p>
<h6>
<a name="log.detailed.sink_frontends.async.h1"></a>
          <span class="phrase"><a name="log.detailed.sink_frontends.async.ordering_log_records"></a></span><a class="link" href="sink_frontends.html#log.detailed.sink_frontends.async.ordering_log_records">Ordering
          log records</a>
        </h6>
<p>
          Record ordering can be useful to alleviate the <a class="link" href="../rationale/why_weak_record_ordering.html" title="Why log records are weakly ordered in a multithreaded application?">weak
          record ordering</a> issue present in multithreaded applications.
        </p>
<p>
          Ordering queueing strategies introduce a small latency to the record processing.
          The latency duration and the ordering predicate can be specified on the
          frontend construction. It may be useful to employ the <a class="link" href="utilities.html#log.detailed.utilities.record_ordering" title="Log record ordering">log
          record ordering tools</a> to implement ordering predicates.
        </p>
<p>
</p>
<pre class="programlisting"><span class="comment">// Complete sink type</span>
<span class="keyword">typedef</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">asynchronous_sink</span><span class="special">&lt;</span>
    <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span><span class="special">,</span>
    <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">unbounded_ordering_queue</span><span class="special">&lt;</span>                                             <a class="co" name="log.detailed.sink_frontends.async.c6" href="sink_frontends.html#log.detailed.sink_frontends.async.c7"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a>
        <span class="identifier">logging</span><span class="special">::</span><span class="identifier">attribute_value_ordering</span><span class="special">&lt;</span>                                       <a class="co" name="log.detailed.sink_frontends.async.c8" href="sink_frontends.html#log.detailed.sink_frontends.async.c9"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a>
            <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">,</span>                                                        <a class="co" name="log.detailed.sink_frontends.async.c10" href="sink_frontends.html#log.detailed.sink_frontends.async.c11"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a>
            <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="special">&gt;</span>                                            <a class="co" name="log.detailed.sink_frontends.async.c12" href="sink_frontends.html#log.detailed.sink_frontends.async.c13"><img src="../../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a>
        <span class="special">&gt;</span>
    <span class="special">&gt;</span>
<span class="special">&gt;</span> <span class="identifier">sink_t</span><span class="special">;</span>

<span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">init_logging</span><span class="special">()</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// Create a backend and initialize it with a stream</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;</span> <span class="identifier">backend</span> <span class="special">=</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">sinks</span><span class="special">::</span><span class="identifier">text_ostream_backend</span> <span class="special">&gt;();</span>
    <span class="identifier">backend</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span> <span class="special">&gt;(&amp;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">clog</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">null_deleter</span><span class="special">()));</span>

    <span class="comment">// Wrap it into the frontend and register in the core</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;</span> <span class="identifier">sink</span><span class="special">(</span><span class="keyword">new</span> <span class="identifier">sink_t</span><span class="special">(</span>
        <span class="identifier">backend</span><span class="special">,</span>                                                                 <a class="co" name="log.detailed.sink_frontends.async.c14" href="sink_frontends.html#log.detailed.sink_frontends.async.c15"><img src="../../../../../../doc/src/images/callouts/5.png" alt="5" border="0"></a>
        <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">order</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">make_attr_ordering</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="special">&gt;(</span>           <a class="co" name="log.detailed.sink_frontends.async.c16" href="sink_frontends.html#log.detailed.sink_frontends.async.c17"><img src="../../../../../../doc/src/images/callouts/6.png" alt="6" border="0"></a>
            <span class="string">"LineID"</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="special">&gt;()),</span>
        <span class="identifier">keywords</span><span class="special">::</span><span class="identifier">ordering_window</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">posix_time</span><span class="special">::</span><span class="identifier">seconds</span><span class="special">(</span><span class="number">1</span><span class="special">)</span>                <a class="co" name="log.detailed.sink_frontends.async.c18" href="sink_frontends.html#log.detailed.sink_frontends.async.c19"><img src="../../../../../../doc/src/images/callouts/7.png" alt="7" border="0"></a>
    <span class="special">));</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">add_sink</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>

    <span class="comment">// You can manage filtering and formatting through the sink interface</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_filter</span><span class="special">(</span><span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="identifier">warning</span><span class="special">);</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">set_formatter</span>
    <span class="special">(</span>
        <span class="identifier">expr</span><span class="special">::</span><span class="identifier">stream</span>
            <span class="special">&lt;&lt;</span> <span class="string">"Level: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">attr</span><span class="special">&lt;</span> <span class="identifier">severity_level</span> <span class="special">&gt;(</span><span class="string">"Severity"</span><span class="special">)</span>
            <span class="special">&lt;&lt;</span> <span class="string">" Message: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">expr</span><span class="special">::</span><span class="identifier">smessage</span>
    <span class="special">);</span>

    <span class="comment">// You can also manage backend in a thread-safe manner</span>
    <span class="special">{</span>
        <span class="identifier">sink_t</span><span class="special">::</span><span class="identifier">locked_backend_ptr</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">locked_backend</span><span class="special">();</span>
        <span class="identifier">p</span><span class="special">-&gt;</span><span class="identifier">add_stream</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_shared</span><span class="special">&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ofstream</span> <span class="special">&gt;(</span><span class="string">"sample.log"</span><span class="special">));</span>
    <span class="special">}</span> <span class="comment">// the backend gets released here</span>

    <span class="keyword">return</span> <span class="identifier">sink</span><span class="special">;</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<div class="calloutlist"><table border="0" summary="Callout list">
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c7"></a><a href="#log.detailed.sink_frontends.async.c6"><img src="../../../../../../doc/src/images/callouts/1.png" alt="1" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              log record queueing strategy
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c9"></a><a href="#log.detailed.sink_frontends.async.c8"><img src="../../../../../../doc/src/images/callouts/2.png" alt="2" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              log record ordering predicate type
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c11"></a><a href="#log.detailed.sink_frontends.async.c10"><img src="../../../../../../doc/src/images/callouts/3.png" alt="3" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              attribute value type
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c13"></a><a href="#log.detailed.sink_frontends.async.c12"><img src="../../../../../../doc/src/images/callouts/4.png" alt="4" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              optional, attribute value comparison predicate; <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span></code>
              equivalent is used by default
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c15"></a><a href="#log.detailed.sink_frontends.async.c14"><img src="../../../../../../doc/src/images/callouts/5.png" alt="5" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              pointer to the pre-initialized backend
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c17"></a><a href="#log.detailed.sink_frontends.async.c16"><img src="../../../../../../doc/src/images/callouts/6.png" alt="6" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              log record ordering predicate
            </p></td>
</tr>
<tr>
<td width="5%" valign="top" align="left"><p><a name="log.detailed.sink_frontends.async.c19"></a><a href="#log.detailed.sink_frontends.async.c18"><img src="../../../../../../doc/src/images/callouts/7.png" alt="7" border="0"></a> </p></td>
<td valign="top" align="left"><p>
              latency of log record processing
            </p></td>
</tr>
</table></div>
<p>
          In the code sample above the sink frontend will keep log records in the
          internal queue for up to one second and apply ordering based on the log
          record counter of type <code class="computeroutput"><span class="keyword">unsigned</span>
          <span class="keyword">int</span></code>. The <code class="computeroutput"><span class="identifier">ordering_window</span></code>
          parameter is optional and will default to some reasonably small system-specific
          value that will suffice to maintain chronological flow of log records to
          the backend.
        </p>
<p>
          The ordering window is maintained by the frontend even upon stopping the
          internal feeding loop, so that it would be possible to reenter the loop
          without breaking the record ordering. On the other hand, in order to ensure
          that all log records are flushed to the backend one has to call the <code class="computeroutput"><span class="identifier">flush</span></code> method at the end of the application.
        </p>
<p>
</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">stop_logging</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">sink_t</span> <span class="special">&gt;&amp;</span> <span class="identifier">sink</span><span class="special">)</span>
<span class="special">{</span>
    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">shared_ptr</span><span class="special">&lt;</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span> <span class="special">&gt;</span> <span class="identifier">core</span> <span class="special">=</span> <span class="identifier">logging</span><span class="special">::</span><span class="identifier">core</span><span class="special">::</span><span class="identifier">get</span><span class="special">();</span>

    <span class="comment">// Remove the sink from the core, so that no records are passed to it</span>
    <span class="identifier">core</span><span class="special">-&gt;</span><span class="identifier">remove_sink</span><span class="special">(</span><span class="identifier">sink</span><span class="special">);</span>

    <span class="comment">// Break the feeding loop</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">stop</span><span class="special">();</span>

    <span class="comment">// Flush all log records that may have left buffered</span>
    <span class="identifier">sink</span><span class="special">-&gt;</span><span class="identifier">flush</span><span class="special">();</span>

    <span class="identifier">sink</span><span class="special">.</span><span class="identifier">reset</span><span class="special">();</span>
<span class="special">}</span>
</pre>
<p>
        </p>
<p>
          This technique is also demonstrated in the <a href="../../../../../../libs/log/example/async_log/main.cpp" target="_top"><code class="computeroutput"><span class="identifier">async_log</span></code></a> example in the library
          distribution.
        </p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2007-2021 Andrey Semashev<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="sources.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../detailed.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="sink_backends.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
